<!DOCTYPE HTML>
<html lang="en">
<head>
<title>StrSplit() / StringSplit - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The StrSplit function and StringSplit command separate a string into an array of substrings using the specified delimiters." />
<meta name="ahk:equiv-v2" content="commands/StrSplit.htm" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>StrSplit() / StringSplit</h1>
<p>Separates a string into an array of substrings using the specified delimiters.</p>

<h2 id="function">StrSplit() <span class="ver">[v1.1.13+]</span></h2>
<pre class="Syntax">
Array := <span class="func">StrSplit</span>(String <span class="optional">, Delimiters, OmitChars</span>)
Array := <span class="func">StrSplit</span>(String <span class="optional">, Delimiters, OmitChars, MaxParts := -1</span>)  <em>; <span class="ver">[v1.1.28+]</span></em>
</pre>

<h3>Parameters</h3>
<dl>

  <dt>String</dt>
  <dd><p>A string to split.</p></dd>

  <dt>Delimiters</dt>
  <dd><p>If this parameter is blank or omitted, each character of the input string will be treated as a separate substring.</p>
      <p>Otherwise, <em>Delimiters</em> can be either a single string or an array of strings, each of which is used to determine where the boundaries between substrings occur. Since the delimiters are not considered to be part of the substrings themselves, they are never included in the returned array. Also, if there is nothing between a pair of delimiters within the input string, the corresponding array element will be blank.</p>      
      <p>For example: <code>&quot;,&quot;</code> would divide the string based on every occurrence of a comma. Similarly, <code>[A_Tab, A_Space]</code> would create a new array element every time a space or tab is encountered in the input string.</p></dd>

  <dt>OmitChars</dt>
  <dd><p>An optional list of characters (case sensitive) to exclude from the beginning and end of each array element. For example, if <em>OmitChars</em> is <code>" `t"</code>, spaces and tabs will be removed from the beginning and end (but not the middle) of every element.</p>
      <p>If <em>Delimiters</em> is blank, <em>OmitChars</em> indicates which characters should be excluded from the array.</p></dd>

  <dt>MaxParts <span class="ver">[v1.1.28+]</span></dt>
  <dd><p>The maximum number of substrings to return. If non-zero, the string is split a maximum of <em>MaxParts</em>-1 times and the remainder of the string is returned in the last substring (excluding any leading or trailing <em>OmitChars</em>). If omitted or -1, there is no limit.</p></dd>

</dl>

<h3>Return Value</h3>
<p>This function returns an <a href="../Objects.htm#Usage_Simple_Arrays">array</a> (object) of strings.</p>

<h3>Examples</h3>
<pre class="NoIndent">TestString := "This is a test."
word_array := StrSplit(TestString, A_Space, ".")  <em>; Omits periods.</em>
MsgBox % "The 4th word is " word_array[4]

Colors := "red,green,blue"
ColorArray := StrSplit(Colors, ",")
Loop % ColorArray.MaxIndex()
{
    this_color := ColorArray[A_Index]
    MsgBox, Color number %A_Index% is %this_color%.
}</pre>

<h2 id="command">StringSplit</h2>
<p class="warning"><strong>Deprecated:</strong> This command is not recommended for use in new scripts. Use the <a href="#function">StrSplit</a> function instead.</p>
<pre class="Syntax"><span class="func">StringSplit</span>, OutputArray, InputVar <span class="optional">, Delimiters, OmitChars</span></pre>

<h3>Parameters</h3>
<dl>

  <dt>OutputArray</dt>
  <dd><p>The name of the <a href="../misc/Arrays.htm#pseudo">pseudo-array</a> in which to store each substring extracted from <em>InputVar</em>. For example, if MyArray is specified, the command will put the number of substrings produced (0 if none) into MyArray0, the first substring into MyArray1, the second into MyArray2, and so on.</p>
      <p>Within a <a href="../Functions.htm">function</a>, to create a pseudo-array that is global instead of local, <a href="../Functions.htm#Global">declare</a> MyArray0 as a global variable inside the function (the converse is true for <a href="../Functions.htm#AssumeGlobal">assume-global</a> functions). However, it is often also necessary to declare each element, due to a <a href="../Functions.htm#ArrayConfusion">common source of confusion</a>. For more details, see <a href="../Functions.htm#PseudoArrays">Functions</a>.</p></dd>

  <dt>InputVar</dt>
  <dd><p>The name of the variable whose contents will be analyzed.  Do not enclose the name in percent signs unless you want the <em>contents</em> of the variable to be used as the name.</p>
      <p class="note"><strong>Note</strong>: <em>InputVar</em> must not be one of the variables in <em>OutputArray</em>.</p></dd>

  <dt>Delimiters</dt>
  <dd><p>If this parameter is blank or omitted, each character of <em>InputVar</em> will be treated as a separate substring.</p>
      <p>Otherwise, <em>Delimiters</em> contains one or more characters  (case sensitive), each of which is used to determine where the boundaries between substrings occur in <em>InputVar</em>. Since the delimiter characters are not considered to be part of the substrings themselves, they are never copied into <em>OutputArray</em>. Also, if there is nothing between a pair of delimiters within <em>InputVar</em>, the corresponding array element will be blank.</p>      
      <p>For example: <code>`,</code> (an escaped comma) would divide the string based on every occurrence of a comma. Similarly, %A_Tab%%A_Space% would create a new array element every time a space or tab is encountered in <em>InputVar</em>.</p>
      <p>To use a string as a delimiter rather than a character, first use <a href="StringReplace.htm">StringReplace</a> to replace all occurrences of the string with a single character that is never used literally in the text. Consider this example, which uses the string &lt;br&gt; as a delimiter:</p>
<pre>StringReplace, NewHTML, HTMLString, &lt;br&gt;, ``, All  <em>; Replace each &lt;br&gt; with an accent.</em>
StringSplit, MyArray, NewHTML, ``  <em>; Split the string based on the accent character.</em></pre></dd>

  <dt>OmitChars</dt>
  <dd><p>An optional list of characters (case sensitive) to exclude from the beginning and end of each array element. For example, if <em>OmitChars</em> is <code>%A_Space%%A_Tab%</code>, spaces and tabs will be removed from the beginning and end (but not the middle) of every element.</p>
      <p>If <em>Delimiters</em> is blank, <em>OmitChars</em> indicates which characters should be excluded from the array.</p>
      <p>Unlike the last parameter of most other commands, commas in <em>OmitChars</em> must be escaped (`,).</p></dd>

</dl>

<h3>Remarks</h3>
<p>If the array elements already exist, the command will change the values of only the first N elements, where N is the number of substrings present in <em>InputVar</em>. Any elements beyond N that existed beforehand will be unchanged. Therefore, it is safest to use the zero element (MyArray0) to determine how many items were actually produced by the command.</p>

<h3>Examples</h3>
<pre class="NoIndent">TestString := "This is a test."
StringSplit, word_array, TestString, %A_Space%, .  <em>; Omits periods.</em>
MsgBox, The 4th word is %word_array4%.

Colors := "red,green,blue"
StringSplit, ColorArray, Colors, `,
Loop, %ColorArray0%
{
    this_color := ColorArray%A_Index%
    MsgBox, Color number %A_Index% is %this_color%.
}</pre>
<h2>Remarks</h2>
<p>Whitespace characters such as spaces and tabs will be preserved unless those characters are themselves delimiters or included in <em>OmitChars</em>. Tabs and spaces can be trimmed from both ends of any variable by calling the <a href="Trim.htm">Trim</a> function. For example: <code>MyArray1 := Trim(MyArray1)</code>.</p>
<p>To split a string that is in standard CSV (comma separated value) format, use a <a href="LoopParse.htm">parsing loop</a> since it has  built-in CSV handling.</p>
<p>To arrange the fields in a different order prior to splitting them, use the <a href="Sort.htm">Sort</a> command.</p>
<p>If you do not need the substrings to be permanently stored in memory, consider using a <a href="LoopParse.htm">parsing loop</a> -- especially if <em>InputVar</em> is very large, in which case a large amount of memory would be saved. For example:</p>
<pre>Colors := "red,green,blue"
Loop, parse, Colors, `,
    MsgBox Color number %A_Index% is %A_LoopField%.</pre>

<h2>Related</h2>
<p><a href="LoopParse.htm">Parsing loop</a>, <a href="../misc/Arrays.htm">Arrays</a>, <a href="Sort.htm">Sort</a>, <a href="SplitPath.htm">SplitPath</a>, <a href="IfInString.htm">IfInString</a>, <a href="StringGetPos.htm">StringGetPos</a>, <a href="StringMid.htm">StringMid</a>, <a href="StringTrimLeft.htm">StringTrimLeft</a>, <a href="StringTrimLeft.htm">StringTrimRight</a>, <a href="StringLen.htm">StrLen() / StringLen</a>, <a href="StringLower.htm">StringLower</a>, <a href="StringLower.htm">StringUpper</a>, <a href="StringReplace.htm">StringReplace</a></p>

</body>
</html>
